UV and UVX Cheatsheet

🚀 The Ultimate uv and uvx Cheatsheet

A Comprehensive Guide for Modern Python Development Official Documentation: docs.astral.sh/uv This cheatsheet provides a deep dive into uv, the blazing-fast, next-generation Python package and project manager. Learn how to replace your entire toolchain (pip, venv, pip-tools, pipx) with a single, cohesive, and incredibly performant tool.

💡 Core Concepts

uv is a package manager and resolver written in Rust by Astral, the team behind the popular Ruff linter. It's designed from the ground up to be a complete, drop-in replacement for the traditional Python packaging toolchain.

• uv: The primary binary. It's an all-in-one tool that handles:
  • Virtual environment creation (venv/virtualenv replacement).
  • Package installation and resolution (pip replacement).
  • Lock file generation (pip-tools replacement).
  • Project and workspace management (Poetry/PDM replacement).
  • Python version management and installation (pyenv partial replacement).
• uvx: This is not a separate tool to install. uvx is a convenient, built-in alias for uv tool run. It's the modern, fast equivalent of pipx, used to run CLI tools in temporary, isolated environments without polluting your project or global space.

• Key Advantages:
  • ⚡ Blistering Speed: Benchmarks show uv is 10-100x faster than pip and pip-tools. This is not just an incremental improvement; it fundamentally changes development feedback loops.
  • 💾 Intelligent Caching: uv employs a global cache for package metadata and distributions. This means a package downloaded for one project is instantly available for another, dramatically reducing redundant downloads and installation times.
  • 🛠️ Unified Workflow: Say goodbye to juggling multiple tools. uv provides a single, consistent CLI for nearly every packaging task, simplifying your workflow and reducing cognitive overhead.

  📦 Installation

  uv is distributed as a single, standalone binary, making installation trivial.
  • Multi-Platform Installation:

Platform	Command
Linux/macOS	curl -LsSf https://astral.sh/uv/install.sh
Windows	powershell -c "irm https://astral.sh/uv/install.ps1
pipx	pipx install uv
Homebrew	brew install uv
Cargo	cargo install --locked uv
How to install non-system Python versions	uv can automatically download and manage Python versions for you, placing them in a location uv can always find.

Install a specific version of Python making it available to uv

uv python install 3.12

Install the latest stable version

uv python install

Post-Install Verification Steps

• Verify the uv installation: uv --version

Expected output: uv 0.1.41 (or newer)

List available Python interpreters that uv can find or has installed:

uv python list

** This will show system pythons, pyenv pythons, and uv-installed pythons.**

🔄 Workflow Comparison

Understanding how uv changes the development workflow is key to leveraging its power.

graph TD
    subgraph "A. Pure UV/UVX Workflow (Recommended)"
        direction LR
        A1(uv init) --> A2(uv add <pkg>);
        A2 --> A3(uv lock);
        A3 --> A4(uv sync);
        A4 --> A5(uvx <tool>);
    end

    subgraph "B. Traditional pip/venv Workflow (The Old Way)"
        direction LR
        B1(python -m venv .venv) --> B2(pip install <pkg>);
        B2 --> B3(pip freeze > reqs.txt);
        B3 --> B4(pip install -r reqs.txt);
        B4 --> B5(pipx run <tool>);
    end

    subgraph "C. Hybrid UV + pip/venv Workflow (Migration)"
        direction LR
        C1(python -m venv .venv) --> C2(pip install uv);
        C2 --> C3(uv pip install <pkg>);
        C3 --> C4(uv pip compile...);
        C4 --> C5(uv pip sync...);
    end

Pure UV/UVX Workflow:

This workflow leverages uv for everything, providing the most streamlined and performant experience. You never touch pip or venv directly.

• Initialize Project: Creates pyproject.toml and a .python-version file. uv init
• Create Environment: uv automatically creates a .venv using the pinned Python version on the first command (like add or sync). To create it explicitly with Python 3.11: uv venv -p 3.11
• Manage Dependencies: Adds requests to pyproject.toml and installs it. Adds ruff as a dev dependency. uv add requests uv add "ruff" --dev
• Lock & Sync: uv automatically updates uv.lock when dependencies change. A collaborator pulls the repo and runs sync to get an identical environment.

Install main and dev dependencies from uv.lock

uv sync --dev

• Upgrade Process: uvx is not used for upgrading project dependencies. Use uv add --upgrade. uv add --upgrade requests ruff # Upgrade specified packages

Traditional pip/venv Workflow:

This is the classic, often slower, and more fragmented workflow.

• Create Environment: python3.11 -m venv .venv source .venv/bin/activate
• Install & Freeze: Manually install packages and then freeze the state. pip install requests pip freeze > requirements.txt
• Manual Dependency Management: Edit requirements.txt manually to add new packages or update versions.
• Environment Recreation: A collaborator must recreate the environment. This does not guarantee identical transitive dependencies. pip install -r requirements.txt

Hybrid UV + pip/venv Workflow:

Use this to introduce uv's speed benefits into an existing project without a full migration.

• Standard venv creation: Start with your existing process. python3 -m venv .venv source .venv/bin/activate
• UV Installation within environment: Install uv into the active virtual environment. pip install uv
• Mix of commands: Use uv pip as a drop-in pip replacement for massive speed gains.

Instead of: pip install -r requirements.txt

uv pip install -r requirements.txt

• Lock file advantages: Use uv to create a fully-resolved, cross-platform lock file from your requirements.txt. This is a huge win for reproducibility. uv pip compile requirements.txt -o requirements.lock

Now, anyone (or CI) can sync with perfect reproducibility

uv pip sync requirements.lock

🐍 Python Version Management

uv excels at managing which Python version your project uses.

• Specifying versions during environment creation:

  • uv can find system-installed Pythons or download new ones on the fly.

  Use a version you have (e.g., 3.10)

uv venv -p 3.10

uv will download and install 3.12 if not found on your system

uv venv -p 3.12

Using .python-version files:

• This is the recommended way to pin a project's Python version. uv init creates this file for you.

Create the file manually

echo "3.11.8" > .python-version

Now, simply run uv venv and it will automatically use 3.11.8

If not found, it will offer to install it.

uv venv

• Cross-version dependency resolution:

  • You can generate a lock file for a Python version you don't even have installed. This is a killer feature for library authors who need to support multiple Python versions.

Generate a lock file compatible with Python 3.8, even if you are on 3.11

uv lock --python-version 3.8

• Multi-environment testing workflows (CI/CD): .github/workflows/ci.yml

jobs:
  test:
    strategy:
      matrix:
        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
    steps:
    - uses: actions/checkout@v4
    - uses: astral-sh/setup-uv@v1
    - name: Install and Sync Dependencies
      run: uv sync --dev --python-version ${{ matrix.python-version }}
    - name: Run Tests
      run: uv run pytest

Advanced Features

Cross-platform lock files:

• A single uv.lock file contains dependency metadata for different platforms (Windows, macOS, Linux) and architectures. uv sync on any machine will install the correct platform-specific wheels.

warning

⚠️ Danger Note: This works perfectly if packages provide wheels for all platforms or have pure Python source distributions. If a package requires compilation and is missing a wheel for a specific target, the install on that target may fail unless system build tools are available.

Private repository configuration:

• Configure private indexes in pyproject.toml. For authentication, use environment variables.

pyproject.toml

[tool.uv.pip]
index-url = "https://pypi.org/simple"
extra-index-url = ["https://my-private-repo.com/simple"]

In your shell or CI secrets

export UV_EXTRA_INDEX_URL="https://user:password@my-private-repo.com/simple"

• Dependency resolution strategies:

  • uv defaults to highest (like pip). You can change this to test dependency bounds for libraries.

  Test against the lowest allowed versions of your direct dependencies

uv pip install --resolution=lowest-direct -r requirements.txt

• CI/CD optimizations (caching, fast installs):

  • Use astral-sh/setup-uv@v1: This GitHub Action correctly installs uv and sets up its cache.
  • Cache uv's Global Cache: Drastically speeds up builds.

    - name: Cache uv
    uses: actions/cache@v4
    with:
       path: ~/.cache/uv
       : ${{ runner.os }}-uv-${{ hashFiles('**/uv.lock') }}

• name: Install dependencies from lockfile run: uv sync --frozen

  • Fast Installs: --frozen ensures no time is wasted checking for new versions online if the lock file is present.

• uv.toml configuration examples:

  • For configuration that doesn't belong in pyproject.toml (e.g., in a parent directory), create a uv.toml file.

  ~/.config/uv/uv.toml - Example for setting a global download directory

cache-dir = "/path/to/shared/cache"

[tool.uv.pip]
no-deps = true # Globally disable dependency installation

🔧 Troubleshooting Guide

• Python version not found:
  • Problem: uv venv -p 3.9 fails saying "Python version 3.9 not found".
  • Solution 1 (List available): See what uv can find: uv python list. Use one of the listed versions.
  • Solution 2 (Install it): Let uv install it for you: uv python install 3.9.
  • Solution 3 (pyenv): Ensure pyenv is set up correctly in your shell's rc file (.zshrc, .bashrc) so uv can discover it.
• Dependency conflict resolution:
  • Problem: uv lock or uv add fails with a resolution error.
  • Solution 1 (Inspect Tree): Use uv pip tree to visualize the dependency graph and find the source of the conflict.
  • Solution 2 (Manual Pinning): Explicitly add the conflicting transitive dependency to your pyproject.toml with a compatible version number.
  • Solution 3 (Overrides): As a last resort, use [tool.uv.overrides] in pyproject.toml to force a specific version of a package, ignoring its own dependency constraints. > ⚠️ Warning: This can lead to a broken environment if not used carefully.
• Cache management and cleanup:
  • Problem: The cache is taking up too much space or you suspect a corrupted package.
  • Solution: Use the uv cache commands.# Show the cache directory path

uv cache dir

Remove all cached packages and other data

uv cache clean

Platform-specific installation issues:

• Problem: uv sync works on your macOS machine but fails in a Linux Docker container.
• Cause: Likely a package that has a macOS wheel but no Linux wheel and fails to build from source in the container (e.g., missing a system library like gcc).
• Solution: Check the failing package's documentation. You may need to install system-level dependencies in your Dockerfile before running uv sync (e.g., apt-get update && apt-get install -y build-essential).

📊 Command Reference Table

Task	Pure UV Command	Traditional pip/venv Command	Hybrid Approach Command
Env Creation	uv venv -p 3.11	python3.11 -m venv .venv`	python3.11 -m venv .venv
Activate Env	source .venv/bin/activate	source .venv/bin/activate	source .venv/bin/activate
Install Package	uv add requests	pip install requests	uv pip install requests
Install from File	uv sync --dev (uses uv.lock)	pip install -r requirements.txt	uv pip install -r requirements.txt
Generate Lock File	uv lock (or auto on add)	pip freeze > requirements.txt	uv pip compile req.txt -o req.lock
Sync from Lock	uv sync	pip install -r requirements.txt	uv pip sync req.lock
Upgrade Packages	uv add --upgrade pkg	pip install --upgrade <pkg>	uv pip install --upgrade <pkg>
List Packages	uv pip list	pip list	uv pip list
Show Dep. Tree	uv pip tree	pipdeptree (separate install)	uv pip tree
Run Tool (Isolated)	uvx black .	pipx run black .	uvx black .
Run Project Script	uv run my_script	python -m my_app.cli	uv run my_script